home *** CD-ROM | disk | FTP | other *** search
- /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
- /* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
- *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is mozilla.org code.
- *
- * The Initial Developer of the Original Code is
- * Netscape Communications Corporation.
- * Portions created by the Initial Developer are Copyright (C) 1998
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either of the GNU General Public License Version 2 or later (the "GPL"),
- * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- *
- * ***** END LICENSE BLOCK ***** */
-
- #include "nsIAsyncInputStream.idl"
- #include "nsIAsyncOutputStream.idl"
-
- interface nsIMemory;
-
- /**
- * nsIPipe represents an in-process buffer that can be read using nsIInputStream
- * and written using nsIOutputStream. The reader and writer of a pipe do not
- * have to be on the same thread. As a result, the pipe is an ideal mechanism
- * to bridge data exchange between two threads. For example, a worker thread
- * might write data to a pipe from which the main thread will read.
- *
- * Each end of the pipe can be either blocking or non-blocking. Recall that a
- * non-blocking stream will return NS_BASE_STREAM_WOULD_BLOCK if it cannot be
- * read or written to without blocking the calling thread. For example, if you
- * try to read from an empty pipe that has not yet been closed, then if that
- * pipe's input end is non-blocking, then the read call will fail immediately
- * with NS_BASE_STREAM_WOULD_BLOCK as the error condition. However, if that
- * pipe's input end is blocking, then the read call will not return until the
- * pipe has data or until the pipe is closed. This example presumes that the
- * pipe is being filled asynchronously on some background thread.
- *
- * The pipe supports nsIAsyncInputStream and nsIAsyncOutputStream, which give
- * the user of a non-blocking pipe the ability to wait for the pipe to become
- * ready again. For example, in the case of an empty non-blocking pipe, the
- * user can call AsyncWait on the input end of the pipe to be notified when
- * the pipe has data to read (or when the pipe becomes closed).
- *
- * NS_NewPipe2 and NS_NewPipe provide convenient pipe constructors. In most
- * cases nsIPipe is not actually used. It is usually enough to just get
- * references to the pipe's input and output end. In which case, the pipe is
- * automatically closed when the respective pipe ends are released.
- */
- [scriptable, uuid(f4211abc-61b3-11d4-9877-00c04fa0cf4a)]
- interface nsIPipe : nsISupports
- {
- /**
- * initialize this pipe
- */
- void init(in boolean nonBlockingInput,
- in boolean nonBlockingOutput,
- in unsigned long segmentSize,
- in unsigned long segmentCount,
- in nsIMemory segmentAllocator);
-
- /**
- * The pipe's input end, which also implements nsISearchableInputStream.
- */
- readonly attribute nsIAsyncInputStream inputStream;
-
- /**
- * The pipe's output end.
- */
- readonly attribute nsIAsyncOutputStream outputStream;
- };
-
- /**
- * XXX this interface doesn't really belong in here. It is here because
- * currently nsPipeInputStream is the only implementation of this interface.
- */
- [scriptable, uuid(8C39EF62-F7C9-11d4-98F5-001083010E9B)]
- interface nsISearchableInputStream : nsISupports
- {
- /**
- * Searches for a string in the input stream. Since the stream has a notion
- * of EOF, it is possible that the string may at some time be in the
- * buffer, but is is not currently found up to some offset. Consequently,
- * both the found and not found cases return an offset:
- * if found, return offset where it was found
- * if not found, return offset of the first byte not searched
- * In the case the stream is at EOF and the string is not found, the first
- * byte not searched will correspond to the length of the buffer.
- */
- void search(in string forString,
- in boolean ignoreCase,
- out boolean found,
- out unsigned long offsetSearchedTo);
- };
-
- %{C++
-
- /**
- * NS_NewPipe2
- *
- * This function supercedes NS_NewPipe. It differs from NS_NewPipe in two
- * major ways:
- * (1) returns nsIAsyncInputStream and nsIAsyncOutputStream, so it is
- * not necessary to QI in order to access these interfaces.
- * (2) the size of the pipe is determined by the number of segments
- * times the size of each segment.
- *
- * @param pipeIn
- * resulting input end of the pipe
- * @param pipeOut
- * resulting output end of the pipe
- * @param nonBlockingInput
- * true specifies non-blocking input stream behavior
- * @param nonBlockingOutput
- * true specifies non-blocking output stream behavior
- * @param segmentSize
- * specifies the segment size in bytes (pass 0 to use default value)
- * @param segmentCount
- * specifies the max number of segments (pass 0 to use default value)
- * passing PR_UINT32_MAX here causes the pipe to have "infinite" space.
- * this mode can be useful in some cases, but should always be used with
- * caution. the default value for this parameter is a finite value.
- * @param segmentAlloc
- * pass reference to nsIMemory to have all pipe allocations use this
- * allocator (pass null to use the default allocator)
- */
- extern NS_COM nsresult
- NS_NewPipe2(nsIAsyncInputStream **pipeIn,
- nsIAsyncOutputStream **pipeOut,
- PRBool nonBlockingInput = PR_FALSE,
- PRBool nonBlockingOutput = PR_FALSE,
- PRUint32 segmentSize = 0,
- PRUint32 segmentCount = 0,
- nsIMemory *segmentAlloc = nsnull);
-
- /**
- * NS_NewPipe
- *
- * Preserved for backwards compatibility. Plus, this interface is more
- * amiable in certain contexts (e.g., when you don't need the pipe's async
- * capabilities).
- *
- * @param pipeIn
- * resulting input end of the pipe
- * @param pipeOut
- * resulting output end of the pipe
- * @param segmentSize
- * specifies the segment size in bytes (pass 0 to use default value)
- * @param maxSize
- * specifies the max size of the pipe (pass 0 to use default value)
- * number of segments is maxSize / segmentSize, and maxSize must be a
- * multiple of segmentSize. passing PR_UINT32_MAX here causes the
- * pipe to have "infinite" space. this mode can be useful in some
- * cases, but should always be used with caution. the default value
- * for this parameter is a finite value.
- * @param nonBlockingInput
- * true specifies non-blocking input stream behavior
- * @param nonBlockingOutput
- * true specifies non-blocking output stream behavior
- * @param segmentAlloc
- * pass reference to nsIMemory to have all pipe allocations use this
- * allocator (pass null to use the default allocator)
- */
- inline nsresult
- NS_NewPipe(nsIInputStream **pipeIn,
- nsIOutputStream **pipeOut,
- PRUint32 segmentSize = 0,
- PRUint32 maxSize = 0,
- PRBool nonBlockingInput = PR_FALSE,
- PRBool nonBlockingOutput = PR_FALSE,
- nsIMemory *segmentAlloc = nsnull)
- {
- PRUint32 segmentCount;
- if (segmentSize == 0)
- segmentCount = 0; // use default
- else
- segmentCount = maxSize / segmentSize;
-
- nsIAsyncInputStream *in;
- nsIAsyncOutputStream *out;
- nsresult rv = NS_NewPipe2(&in, &out, nonBlockingInput, nonBlockingOutput,
- segmentSize, segmentCount, segmentAlloc);
- if (NS_FAILED(rv)) return rv;
-
- *pipeIn = in;
- *pipeOut = out;
- return NS_OK;
- }
-
- %}
-